Suppress speaker echo on the microphone channel - #113

Measures how much of the interviewer's audio the microphone re-captures when
the candidate is on speakers. Reports three numbers per machine: the signed
arrival-order delay between the two channels, the correlation peak at that
lag, and the echo return loss.

The sign matters and is the reason the search window is two-sided. The
acoustic path is always mic-after-speaker, but what is measured here is
arrival order at the worklet, and Chromium's getDisplayMedia loopback path
carries its own latency - so on a machine where it is the slower of the two,
the reference arrives after the echo it explains.

The window searched is wider than any gate would ship with, so a peak sitting
at the edge is distinguishable from a window that is too small; the summary
warns when that happens.

An estimate is only accepted while the reference is actually active. A silent
run reached a correlation of 0.53 - two noise floors correlate - so a peak
height alone cannot tell coupling from silence.

Manual, like taskbar-probe.mjs: it needs a desktop session, real speakers and
someone to play audio into them, so it stays out of test/run.mjs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Verifying the correlator against synthetic signals turned up the more
important defect. Delay recovery is exact, including the sign: +120, +300,
-150, -250 and 0 ms all come back to the frame, and the ERL matches the
injected gain. But the coupling verdict was wrong in the dangerous direction.

The search takes the max over ~120 candidate lags, and the max of many
correlations is biased upward, so unrelated signals score far higher than
intuition suggests: 0.53 on pure silence, 0.57 on two independent bursty
signals. A CORR_MIN of 0.5 calls both of those coupled, and a false "coupled"
on a headphone user is what would lead a gate to cut a microphone that was
never echoing anything.

Prominence - the peak's height above the median lag - separates them cleanly:
0.28 for the unrelated pair against 0.87-1.13 for a real echo. Both ends of
that gap are optimistic, so the threshold is a starting point to be re-derived
from real runs, and the raw numbers are printed every second regardless.

Also: reject unknown arguments and a non-positive --seconds. A mistyped
--noaec was silently ignored, which runs with echo cancellation ON and reports
a plausible number for the configuration you were trying to rule out; a
non-numeric --seconds reached setTimeout as NaN and ended the run before it
started, which reads like a headphone result.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Review of the branch, plus the merge of main, turned up six ways the work
reported something that was not true.

The merge is the substantive one. main added two more microphone captures
while this branch was open: mock-transcription.service.ts, which inlines its
own copy of the three processing flags, and the settings microphone test,
which opens with `audio: true` and so takes whatever Chromium defaults to.
Both textually merged clean and both defeat the point of the change - "one
place to flip them from" is not one place if three callers spell it out
themselves. micConstraints is exported and used by all three. The test meter
case has a second edge: opened as `true`, the level shown while picking a
device is measured through different processing than the session it exists to
predict.

In the probe:

The stall guard counted the report it was about to refuse to print. `coupled`
on a stalled report is the verdict of an estimate that ran against audio which
is no longer arriving, so a capture that died while coupled kept voting on the
headline finding - the exact thing the counters were added to stop. Both health
checks now run before the counters.

The frame counter cannot see an unplugged microphone, though the comment
claimed it. The worklet is pulled by the destination for the life of the
context and zero-pads a missing input by design, so frames keep arriving at
100/s after a track ends while the columns decay quietly toward the noise
floor. Ended tracks are reported separately and named. `muted` is deliberately
not used - it toggles on ordinary silence on some platforms and would discard
most of a legitimately quiet run.

The first report latched `stalled` permanently. lastFrames starts at 0, so a
report that lands before the graph produces its first frame looks exactly like
a capture that died, and put a "re-run this" warning on the summary of a run
that then went fine. Before the first frame is now distinguished from after the
last one.

A suspended AudioContext produced a silent run with no explanation: no frames,
a table of blanks, and a summary reading "no coupling" - the headphone verdict,
from a probe that never listened. Resumed if suspended.

"No coupling" could print directly underneath a non-zero count of accepted
coupled estimates. Estimates run twice a second and reports are sampled once,
so intermittent coupling can enter `samples` without a report tick landing on
it. The headphone verdict now has to clear both counters.

Also: a loopback with no audio track is called out at startup rather than left
to be inferred from an empty ref% column, `--device` lists the labels it did
not match (an exact match against long parenthesised OS strings is the whole
difficulty), `--no-ns` is documented alongside the other two flags, and the
stall warning no longer prints a mangled duplicate of its own second line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…on running it

A test for the invariant the merge already broke once. `main` grew two more
microphone captures while this branch was open, one with the three processing
flags copied out and one opening with `audio: true`, and both merged clean -
there is no conflict, no type error and no lint warning in adding a second
spelling of a constraint object, which is why a checker has to be the thing
that notices. `mic-constraints.test.mjs` walks src/ and fails on any capture
that does not open through micConstraints, naming the file. It fails, verified,
on exactly the regression that reached main. Only src/ is scanned: the probe
varies those flags on purpose, which is its job.

Then the probe, from the point of view of someone actually running it.

Closing the window mid-run ended the process at exit 0 with no summary and
nothing said - indistinguishable, in a scrollback, from a run that finished.
It now says what happened and exits non-zero.

A failed window load rejected into nothing: the window sat at "starting...",
no report ever arrived, and the probe waited for a run that would not begin.

The likeliest failure in this tool is a mistyped --device, whose message is a
list of the device names that do exist - and it was printed under ten frames of
Electron internals. Failures the operator can fix are marked, and print their
message alone. The loopback timeout is one of them, and now says what to check
rather than just that it timed out.

The run asks a person to play audio and stay quiet for 45 seconds while the
only thing moving is a console table. The window counts down the seconds left,
and says when the summary is ready.

Also recorded, not corrected: the correlation overlap shrinks as |lag| grows,
so lags at the edges of the search are estimated from ~20% less audio and the
peak leans very slightly outward. It is ~0.02 against a noise floor that has
measured 0.47-0.57, and it cannot reach the "peak sits at the edge" warning,
which only prints for runs that already have coupled estimates. Correcting it
would move every number the gate is about to be sized from, on judgement rather
than on data, so it is written down where whoever picks the window will read it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

A run where every report was discarded - all stalled, all on a dead capture -
or one too short to produce a single report reached the summary with
totalReports at zero and printed "no coupling (headphones, or nothing played
through them)". That is the worst version of the failure the rest of this
summary is built to avoid: the headphone verdict, stated confidently, from a
probe that took no valid reading at all. It now says so and names both causes.

And the probe was undiscoverable. `taskbar-probe.mjs` is documented in the
section it belongs to; this one was in no section at all, so the next person to
wonder how much of the interviewer the microphone re-captures had no way to
find the tool that answers it. The Headphones section now carries it, together
with the constraints rule and the test that pins it.

CLAUDE.md is edited by hand rather than through prettier: running prettier on it
rewrites 29 unrelated emphasis markers, which is the churn the file's own
Commands section warns about. This change is purely additive.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The probe rejects a mistyped `--noaec` because a silently dropped flag runs
with echo cancellation ON and reports a plausible number for the configuration
you were trying to rule out. The same thing happens one layer down and was not
handled: these constraints are advisory, so Chromium is free to decline them
and say so only in getSettings(). Requested and applied were both printed and
any disagreement left for the reader to spot, in a tool whose entire job is
scoring that A/B - and unlike the typo, this one is not the operator's fault.

Now called out. A device that reports nothing back is said to report nothing,
rather than being read as agreement.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…on-zero

Both found by running the probe rather than reading it.

The first is the same class as everything else in this summary. A run where the
loopback reference never carried audio played nothing for the microphone to
re-capture, so it measured nothing about coupling - and the verdict called that
"no coupling (headphones, or nothing played through them)", offering the two as
equal readings while the ref% column had already told them apart. A run only
measures coupling if something was coupling-capable in the first place. The
silent case now says so and says what to do; the headphone verdict now means
what it says, audio played and the mic did not pick it up.

The second is worse for being invisible. `process.exitCode = 1` followed by
`app.quit()` does not survive - Electron ends the process through its own path
and the status comes out 0 - so every failure the probe reported came back as
success to the shell. A `--device` that does not exist printed its error, its
list of real device names, and exited 0. Both the error paths and the
window-closed-early path went through it. `app.exit` carries the code.

Verified end to end on Windows 11: a run exits 0, a bad --device exits 1 with
its message intact through a pipe, and the four argument guards still exit 2.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ing the reader to edit source

Four findings, all from running the probe against real audio rather than
reading it. The coupled path had never actually executed before this.

**A false "coupled" with the microphone silent.** A run accepted an estimate at
correlation 0.62 and prominence 0.61 with mic% at 0 and an ERL of -56 dB. That
is not an echo 56 dB down, it is the correlator finding structure in a noise
floor, at a lag pinned to the edge of the search window. The thresholds cannot
catch it on their own, because the surface really does have a sharp peak - and
a false "coupled" on a HEADPHONE user is the expensive direction, which is the
entire reason prominence exists. An estimate can only describe re-captured
audio if the microphone recorded any, so that precondition is now required
outright. Real coupling on the same machine runs mic% 24-45 against a floor of
5, and a re-run confirms the verdict still lands at coupled 8/16.

**The search window needed a source edit.** The summary's answer to a peak at
the edge was "widen MIN_LAG_MS/MAX_LAG_MS in renderer.js and re-run". That
warning is not exotic: it fired on the first machine measured, whose peak sat
at -400, the exact floor of the default. Completing a measurement should not
mean editing a renderer file, so the window is `--min-lag=` / `--max-lag=`,
validated like the rest, and the warning now names the flag and the value to
re-run with. Re-run at --min-lag=-1200 the peak lands at -280 and the warning
correctly stops firing.

**The summary and the table describe different populations.** Medians cover
accepted estimates only, which run twice per printed row, so the summary
reported a median correlation of 0.67 when no printed row exceeded 0.53. Read
side by side that looks like an error rather than a better-filtered number.
Said explicitly now.

**INCONCLUSIVE gave advice that did not fit.** It said "re-run with audio
playing for the whole duration" to a run whose ref% sat between 72 and 85 the
entire time - sending someone to redo the thing they had already done
correctly. A reference that was solid throughout means the coupling is marginal
on that machine, which is a finding, not a mistake, and the two cases now get
their own remedy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

"Run each twice and compare erlDb" is not enough method, and the first machine
measured shows why: two 16 s runs of the same unchanged configuration came back
-36.0 and -38.8, a spread of 2.8 dB, while the aec on/off pair differed by
4.3 dB. Two runs cannot separate a real effect from that, and the instruction
as written would have someone record a difference that is mostly noise - in the
one number the constraints decision gets made on.

The header now says to establish the unchanged configuration's spread first and
to discard any difference smaller than it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Making --min-lag/--max-lag settable opened a new way to get the silent wrong
answer this branch keeps closing. The correlator holds 4 s of history and needs
500 ms of overlap at every candidate lag, so a bound beyond +/-3500 ms leaves
correlateAt below its minimum at every lag: it returns null for all of them, no
estimate is ever produced, and the summary reports "no correlated frames" - the
headphone answer, from a window that was too wide to search rather than a mic
that heard nothing.

Checked in the renderer, where the history and overlap numbers are defined, and
raised as a ProbeError so it prints the arithmetic and no stack. --min-lag=-5000
now explains itself and exits 1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The edge warning suggests a wider search, and the previous commit taught the
probe to refuse a window beyond what the correlator can search. On a window
already near that limit the two disagreed: the summary would name a --min-lag
the next run exits 1 on.

The suggestion is clamped to the limit now, and when there is no room left to
widen it says that instead - the delay is a lower bound at that point, and
resolving it needs a longer history rather than a wider window. The limit
travels with the summary from the renderer, where it is derived, rather than
being restated here and left to drift.

Checked across the five cases: peak at the floor and at the ceiling of the
default window, peak at each end of a window already at the limit, and a peak
mid-window that warns about nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

"No correlated frames. Either this is a headphone setup (the good case), or no
audio was playing" was written when that line was the whole answer. It is not
any more: the verdict beneath it now distinguishes NOTHING MEASURED, NOTHING
PLAYED, no coupling and INCONCLUSIVE, using the ref% history and the report
counts. So the line offered "the good case" as a live possibility directly
above a verdict saying nothing had been measured at all - the same unearned
confidence this branch has been removing everywhere else, in the one place that
used to be entitled to it.

It states the fact and stops, in the same label/value shape as the populated
branch. Interpreting is the verdict's job.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md said `ingest()` "deduplicates overlapping segments". Nothing does.
`mergeAdjacentTranscripts` concatenates consecutive blocks from the SAME
speaker inside TRANSCRIPT_INTER_TRANSCRIPT_GAP_MS, and no code anywhere
compares the two channels against each other - grepped for it to be sure.

Worth more than a wording fix, because the file already contradicted itself:
the Headphones section a few hundred lines down says the transcript duplicates
on speakers and that suppressing it is what #111 is for. A reader who took line
63 at face value would conclude the echo duplication was already handled, which
is the exact opposite of the problem this branch exists to measure, and would
have no reason to look further.

Listed on this PR's own checklist and cheap to settle now that the code was
being read anyway.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>